home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr09 / vstsrc.zip / DOC.TXT < prev    next >
Text File  |  1995-02-02  |  49KB  |  988 lines
  1.  
  2.                             VersaTrack V1.2
  3.                             ===============
  4.  
  5.                             
  6.  
  7. 1.0  HISTORY, COPYRIGHTS, RESTRICTIONS AND DISCLAIMERS
  8.      -------------------------------------------------
  9.  
  10. VersaTrack is a derived work, based in part on other similiar work as
  11. described below. It started life as a pet project mostly to learn,
  12. among other things, Windows-NT.
  13.  
  14. My background in programming has been almost exclusively in Unix, but
  15. I use a PC clone running Windows NT at home. That, combined with the lack
  16. of moderately nice, native windows-based satellite tracking software (free
  17. or cheap), opted me to work on VersaTrack. Since I am not an experienced
  18. "Windows" or "OOP" programmer, the code will most probably neither be
  19. efficient, nor optimal in many ways. It is provided "as is" for your hacking
  20. pleasure. As to the accuracy of the results produced by the pragram, all I
  21. can say is that they seem to be adequate for my purposes and jive with some
  22. other freeware that are known to give good results.
  23.  
  24. VersaTrack was intended to be a learning tool more than anything else, and
  25. as such, I hope that it will be used in that spirit. I welcome any and all
  26. comments, refinements, or complaints that anyone might have.
  27. I also hope that others will pick up where I have left off, to make the
  28. code more efficient, and to add more features, specially with respect to
  29. external modules (i.e, executable programs) for radio and rotator control,
  30. for which I've provided complete (or at least near complete) built-in support.
  31.  
  32. Versatrack orbit calculations are based on those that appear in Dr. Manfred
  33. Bester's fine sattrack program (versions 1 and 2, circa 1992 forward).
  34.  
  35. The data from which the maps where generated come from "xsat", an
  36. X-Windows program by David A. Curry (N9MSW).
  37.  
  38. Site coordinates come from various sources, including a couple of
  39. World Almanacs, and also from both of the programs mentioned above.
  40.  
  41. The following are authors' applicable copyright notices:
  42.     
  43.  
  44.          ********** SATTRACK (UNIX VERSION) *********
  45.                                                                               
  46.  Copyright (c) 1992, 1993, 1994 Manfred Bester. All Rights Reserved.        
  47.                                                                               
  48.  Permission to use, copy, modify, and distribute this software and its      
  49.  documentation for educational, research and non-profit purposes, without   
  50.  fee, and without a written agreement is hereby granted, provided that the  
  51.  above copyright notice and the following three paragraphs appear in all    
  52.  copies.                                                                    
  53.                                                                               
  54.  Permission to incorporate this software into commercial products may be    
  55.  obtained from the author, Dr. Manfred Bester, 1636 M. L. King Jr. Way,     
  56.  Berkeley, CA 94709, USA.                                                   
  57.                                                                               
  58.  IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,  
  59.  SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF    
  60.  THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE AUTHOR HAS BEEN ADVISED   
  61.  OF THE POSSIBILITY OF SUCH DAMAGE.                                         
  62.                                                                               
  63.  THE AUTHOR SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT       
  64.  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A    
  65.  PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS"       
  66.  BASIS, AND THE AUTHOR HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,  
  67.  UPDATES, ENHANCEMENTS, OR MODIFICATIONS.                                   
  68.                                                                               
  69.                                                                               
  70.  
  71.          ******** XSAT (for X-Windows) ***********
  72.                                                                               
  73.                                                                               
  74.  Copyright 1992 by David A. Curry                                            
  75.                                                                               
  76.  Permission to use, copy, modify, distribute, and sell this software and its 
  77.  documentation for any purpose is hereby granted without fee, provided that  
  78.  the above copyright notice appear in all copies and that both that copyright
  79.  notice and this permission notice appear in supporting documentation.  The  
  80.  author makes no representations about the suitability of this software for  
  81.  any purpose.  It is provided "as is" without express or implied warranty.   
  82.                                                                               
  83.  David A. Curry, N9MSW                                                       
  84.  Purdue University                                                           
  85.  Engineering Computer Network                                                
  86.  1285 Electrical Engineering Building                                        
  87.  West Lafayette, IN 47907                                                    
  88.  davy@ecn.purdue.edu                                                         
  89.                                                                               
  90.   
  91.  
  92.          ******** VERSATRACK **********
  93.  
  94.  VersaTrack Copyright (c) 1993, 1994 Siamack Navabpour. All Rights Reserved.
  95.  
  96.  Permission is hereby granted to copy, modify and distribute VersaTrack
  97.  in whole, or in part, for educational, non-profit and non-commercial use
  98.  only, free of charge or obligation, and without agreement, provided that
  99.  all copyrights and restrictions noted herein are observed and followed, and
  100.  additionally, that this and all other copyright notices listed herein
  101.  appear unaltered in all copies and in all derived work.
  102.  
  103.  This notice shall not in any way void or superceed any of the other authors
  104.  rights or privilages.
  105.  
  106.  VersaTrack IS PRESENTED FREE AND "AS IS", WITHOUT ANY WARRANTY OR SUPPORT.
  107.  YOU USE IT AT YOUR OWN RISK. The author(s) shall not be liable for any
  108.  direct, indirect, incidental, or consequential damage, loss of profits or
  109.  other tangible or intangible losses or benefits, arising out of or related
  110.  to its use, even if the author(s) has(have) been advised of the possibility
  111.  of such occurance. VersaTrack carries no warranty, explicit or implied,
  112.  including but not limited to the implied warranties of merchantability and
  113.  fitness for a particular purpose.
  114.  
  115.  Siamack Navapbour
  116.  12342 Hunter's Chase Dr. #2114
  117.  Austin, TX 78729
  118.  sia@bga.com -or- sia@realtime.com
  119.  
  120.  
  121. 2.0  PROGRAM REQUIREMENTS AND RESTRICTIONS
  122.      -------------------------------------
  123.  
  124. VersaTrack V1.2 runs under Microsoft's Windows-NT and uses Windows-NT-specific
  125. features. IT WILL NOT RUN UNDER WINDOWS 3.xx. It was developed with MS
  126. WIN32 SDK under Windows NT 3.1 and subsequently moved to Windows NT 3.5.
  127. If you need to make the current version run under 3.1, you have to recompile
  128. it with the the corresponding flag set in the makefile.
  129.  
  130. Little emphasis has been placed on memory conservation, or CPU utilization,
  131. so your system should have plenty of memory and preferrably a floating point
  132. processor. A mouse (or equivalent) pointing device is also required.
  133.  
  134. There are two sets of maps supplied with the present version. One set is
  135. intended for an 800x600 display and the other for 640x480 display. Both
  136. should be used in 256 (or more) color modes. They may or may not work
  137. with other resolutions or color combinations. The 640x480 mode is not
  138. much recommended. The maps do not show the up to date political boundaries
  139. of some of the world countries at the present time. My regrests for that,
  140. but I had no other readily accessible source of data to generate more
  141. pollitically correct maps.
  142.  
  143. In order to use VersaTrack effectively, you need fresh (or at least fairly
  144. fresh) satellite elements. The provided element set may be too old by the
  145. time you begin to use this program, so you should try to obtain a new set.
  146. They are priodically posted over the Usenet news groups and are also available
  147. from AMSAT, ARRL and various other BBSs. VersaTrack can only use the
  148. NASA 2-line element set format. I hope someone will add support for the AMSAT
  149. format.
  150.  
  151.  
  152. 3.0  FEATURES
  153.      --------
  154.  
  155.     o It is free and unrestricted (with copyright restrictions) for
  156.       non-profit use. Source are provided.
  157.  
  158.     o Real-time display of position of any satellite from any site.
  159.       Number of satellite-site combinations restricted only by system
  160.       CPU power and amount of available memory.
  161.  
  162.     o Tabular report and graphical display of ground track for any
  163.       selected satellite.
  164.  
  165.     o Real-time display or ground track report times can be independently
  166.       chosen for each satellite-site pair to be in UTC, "local time", or
  167.       "site local time".
  168.  
  169.     o "Next" rise (AOS) /set (LOS) times display for any chosen
  170.       satellite/site pair, with display of duration, maximum elevation on
  171.       the pass, and the (approximate) direction of travel.
  172.  
  173.     o Two user selectable maps ("U.S.A." and "World"). Options for adding
  174.       custom maps (needs a bit of programming.)
  175.  
  176.     o Easy, one-step selection of options and parameters. There are no
  177.       confusing menu traversal, dialog hierarchy, etc.
  178.  
  179.     o User selectable colors for display of ground tracks, sub-satellite
  180.       points, and annotations.
  181.  
  182.     o Uses "editable" regular ASCII text files for all data bases.
  183.  
  184.     o Fully integrated support for utilization of external modules (i.e.,
  185.       programs) for remote control of devices such as rotators and radios.
  186.      
  187.  
  188. 5.0  KNOWN CAVEATS, BUGS AND GOTCHAS
  189.      -------------------------------
  190.  
  191.     1) Versatrack uses cpu power and memory liberally. For example, if you
  192.        decide to have it display in real-time, 50 satellite/site pairs with
  193.        short update intervals, be prepared to let go of a few megs
  194.        of memory and a good portion (if not all) of your system's CPU juice.
  195.  
  196.     2) Once in a long while, during a real-time display, the 
  197.        sub-satellite point display of a satellite does not get erased (or
  198.        updated) properly, leaving a smudge behind. This problem occurs
  199.        very rarely and a "re-draw" takes care of it.
  200.  
  201.     3) User selectable colors are limitted to 16.
  202.  
  203.     4) Only 800x600- and 640x480-bit resoultion maps are provided.
  204.  
  205.     5) If external control servers are activated at the same time (or
  206.        "close" together), no data may be sent to either one.
  207.  
  208.     6) There is currently no help file avilable.
  209.  
  210.     7) The "More.." and "simulate" buttons in the "Settings" dialog
  211.        box are virtual no-ops.
  212.  
  213.     8) AMSAT orbit parameter's format is not supported in current version.
  214.        It can make a nice little extension project.
  215.  
  216.     9) Some of the time zone offsets given in the sites data file may
  217.        be wrong. You should verify and correct (edit) the data for your
  218.        favorite site(s).
  219.  
  220.    10) When the "hide icon" attribute is selected, the icon will be hidden,
  221.        but the icon title text will not!
  222.  
  223.  
  224. 6.0  INSTALLATION AND SETUP
  225.      ----------------------
  226.  
  227. As distributed, VersaTrack is fully functional and has no time
  228. restrictions, etc. It is free for educational, hobby, and non-commercial use.
  229. However, remember that is a copyrighted derived work and you must
  230. read, understand and observe the terms and conditions associated with
  231. its usage as set forth in this document (See Section 1.0.)
  232.  
  233. To Install verSatrack (sources & executables) you need about 2.7 megabytes
  234. of free disk space. After unpacking the distribution archive, place the files
  235. in a directory that is listed as part of your PATH environment variable.
  236. Then run VERSATRACK.EXE from the command line or via the "run" command of
  237. program manager's File menu. Make sure your system has a mouse or equivalent
  238. pointing device.
  239.  
  240. When Versatrack is run for the first time, it will prompt you for
  241. installation. If you choose to install, you are prompted for names
  242. of data files, the default map to be displayed, the directory where
  243. VersaTrack can find its files, the name of your locale and its
  244. time zone information. The installation is on a "per username" basis.
  245. After all the questions have been answered and verfied, VersaTrack
  246. proceeds to create entries under the following key in the system registry:
  247.  
  248.     \HKEY_CURRENT_USER\Software\VersaTrack\Versatrack 1.2
  249.  
  250. When answering questions during the installation, observe the following
  251. guidelines:
  252.  
  253.     - Avoid misspellings.
  254.     - Make sure any directory name you enter already exists.
  255.     - If your site's name is more than one word (i.e., has spaces),
  256.       enter only *one* space between words. You must also make
  257.       sure that the name you enter appears in exactly the same way in
  258.       the sites file. If it doesn't or they differ in spelling,
  259.       you must edit the entry in the sites file or re-install.
  260.     - Make sure the entry for your site as specified in the site's file
  261.       has the correct time zone name and UTC offset. You should
  262.       edit the site's file and correct these if necessary.
  263.  
  264. Your system must be able to allocate roughly about 1.5 megabytes of memory
  265. before VersaTrack can sucessfully start up. Throughout its execution,
  266. VersaTrack attaches (loads) its dynamic link library (DLL) on an
  267. as needed basis to conserve some memory.
  268.  
  269. If no errors are detected during the installation steps, and if all the
  270. data files are found, VersaTrack displays a map and awaits commands.
  271.  
  272. If you have not read the copyright notices and usage terms, click on
  273. "Copyright".
  274.  
  275. NOTE: THE PRESENT VERSION OF VERSATRACK DOES NOT KNOW ABOUT TIME ZONES
  276. AND DAYLIGHT SAVINGS TIME FOR ANY LOCALE, EXCEPT FOR WHAT IS SPECIFIED
  277. DURING INSTALLATION AND IN THE SITES FILE. IF DAYLIGHT SAVINGS TIME
  278. CHANGES, YOU SHOULD UN-INSTALL AND THEN RE-INSTALL VersaTrack, AND ALSO
  279. EDIT THE SITES FILE TO MODIFY ANY RELEVANT UTC OFFSETS AND TIME ZONE
  280. NAMES.
  281.  
  282. 7.0  OPERATION
  283.      ---------
  284.  
  285. 7.1  Your System Clock or Timer
  286.      --------------------------
  287.  
  288. Be sure to set your system clock or timer as accurately as possible. Based
  289. on the load on your system, it may become necessary to set the clock a
  290. few seconds ahead. This skew may compensate for processing delays and
  291. other load on the system and may yield slightly more accurate results.
  292.  
  293. 7.2  Initialization
  294.  
  295. When you run VersaTrack after it has been installed, it reads the system
  296. registry to determine where where it can find its data files. It then proceeds
  297. to open and read its satellites data base, sites data base, a "modes" file
  298. that may have additional information about one or more of the satellites, the
  299. file containing the "active list", and two rather small files that
  300. contain information regarding external modules with which VersaTrack
  301. can optionally communicate. After all these files are read, VersaTrack
  302. proceeds to read and display a file containing a map.
  303.  
  304. One the initialization phase is finished and the map is displayed,
  305. VersaTrack waits for user commands.
  306.  
  307. 7.3 The Active List and Primary Selection
  308.  
  309. VersaTrack operates on what from here on we will call a "satellite-site pair",
  310. or an "entry". Any number of satellite-site pairs can be chosen by the user.
  311. The list of all such satellite-site pairs is called the active list and can be
  312. stored in an a disk file (the default name of the active lists file is
  313. "active.dat"). Any satellite can be paired with any site, and vice versa. At
  314. any given time, one of the satellite-site pairs in the active list will be
  315. "the primary selection" or "the primary pair". Right after startup, the
  316. primary selection will be the very first entry in the active list. It will not
  317. be remembered from a previous execution. For this reason, it is a good idea to
  318. make sure the first entry in the active list belongs to your "favorite"
  319. satellite and site. You can edit the active list file and move your favorite
  320. entry to the beginning. This file is read only once during VersaTrack's
  321. initialization.
  322.  
  323. During normal operation, you can change the primary selection by first
  324. clicking on the "Settings" button, and then clicking on one of the
  325. entries listed in the box titled "Active List". See Section 8.5 for
  326. another method of changing the primary selection.
  327.  
  328. Except for one, all VersaTrack commands operate on the primary
  329. selection of the active list. The exception is when you click on "RTD"
  330. in VersaTrack's main window menu. RTD stands for "Real-time Display".
  331. RTD will always operate on all items of the active list.
  332.  
  333. To see and manipulate the active list you should use the "Settings" dialog
  334. box by clicking on the button labeled "Settings" at the top of VersaTrack's
  335. main window. The active list appears in the lower right hand corner of
  336. the "Settings" dialog box. For each satellite-site pair in the active list,
  337. VersaTrack keeps a set of attributes. These attributes are the parameters
  338. and flags that are needed during other VersaTrack operations. For example,
  339. the value for "minimum elevation" is used to determine if a satellite is
  340. "visible" from its paired site. By "visible" we loosely mean "radio visible".
  341. Of course in reality natural or man-made obstructions may affect the
  342. "actual" visibility (either in the optical spectrum or otherwise).
  343. Another attribute or parameter is the time format in which a satellite's
  344. position is reported.
  345.  
  346. In the "Settings" dialog box, you can also see the list of all the available
  347. satellites and sites.
  348.  
  349. 7.4 Manipulating the Active List
  350.  
  351. To add an entry to the active list, regardless of whether or not there are
  352. other entries in it, simply choose a satellite and a site, fill in or
  353. click on the values or flags as appropriate, select the time formats
  354. and then click on "Add". If another entry with the same satellite and
  355. the same site does not exist, a new entry will be created. Note however,
  356. that any changes you make will not be stored to disk unless you click on "Save".
  357.  
  358. To delete an entry from the active list, first select the entry by
  359. clicking on the desired entry, in the list box labeled "Active List".
  360. Then click on "Delete".
  361.  
  362. To modify an entry (i.e., a satellite-site pair), select it from the
  363. list box labeled "Active List", then change the attributes as necessary,
  364. and then click on "Modify". Pressing ENTER or RETURN after typing in
  365. a value or a name will cause verification of that what you just entered
  366. to be performed immediately, otherwise all values will be checked for
  367. validity when you click on "Modify", and you may see several error
  368. boxes pop up one after another.
  369.  
  370. Whenever you enter the name of a site or a satellite, via the
  371. edit boxes labeled "Site" or "Satellite" the associated list box will roll
  372. back and forth as you type in the letters. You can have VersaTrack attempt
  373. to complete your "typing" for you by hitting the RETURN or ENTER key early
  374. on. In other words, if the name of the satellite is DO-17, and you have
  375. entered "DO", hitting the RETURN or ENTER keys will finish the entry and
  376. make it "DO-17", provided that no conflicts are detected. Since the first
  377. parts of many of the entries in the satellite and site lists are the same,
  378. this method will not always give you the actual entry you wanted, but
  379. occasionally it can be convenient.
  380.  
  381. Whenever you see an asterisk "*" for a value in one of the controls
  382. in the "Settings" dialog box, it means "use the default value".
  383. You can also enter an astrisk if you want VersaTrack to use the
  384. default value for an attribute.
  385.  
  386. The default value for duration is 1 day, for minimum elevation
  387. it is 0 degrees, for start time it is "the time at the point when
  388. a VersaTrack command is executed that needs the start time", for ground
  389. track step time, it is 30 seconds, and for position update it is 30 seconds.
  390.  
  391. You can save the active list by clicking on the button labeled "Save".
  392. This will re-write the active list file, destroying its previous
  393. contents, so be careful.
  394.  
  395.                          --  IMPORTANT --
  396.         Whenever you actually type in a value (numerical or otherwise),
  397.         in one of the controls, be sure to press the RETURN (or ENTER)
  398.         key when you are finished. The value you enter will not take
  399.         effect (i.e., will not be fully read) unless you press
  400.         the RETURN (or ENTER) key.
  401.  
  402. The entries in active list are stored in the active list file (default
  403. "active.dat") as regular ASCII text records. You can edit this file and
  404. change the entries. VersaTrack does not perform a lot of validity checks on
  405. the contents of its data files, so be very careful, as errors in the data files
  406. may cause the program to behave in an unpredictable fashion, crash, hang,
  407. etc.
  408.  
  409.  
  410. 8.0  MAIN MENU COMMAND BUTTONS
  411.      -------------------------
  412.  
  413. 8.1  Maps
  414.  
  415. Versatrack will try to display the highest resolution map available
  416. for a given display (with a given name). To do this, it will
  417. append one of the following strings, depending on the present
  418. display resolution, to the name of the default map (specified during
  419. installation):
  420.  
  421.     "17"  for 1024x768 bit resolution,
  422.     "86"  for 800x600,
  423.     "54"  for 640x480,
  424.     "oem" for any other resolution.
  425.  
  426. The suffix ".map" is also added. The two standard map names are "world"
  427. and "USA", however, if you wish to display other maps, you can prepare them
  428. using your modified version of mapadj.c, and then specifying the base name
  429. during installation. The current version of VersaTrack has one set of
  430. maps ("world" and "U.S.A.") for 640x480 bit displays and another set for
  431. the 800x600 bit displays. These maps may actually need a bit more "re-touching"
  432. to make them more accurate, but for most practical purposes they are
  433. adequate as they are.
  434.  
  435. If a map's width and/or height is more than the current display size, a
  436. warning message will be issued by VersaTrack, but an attempt will be made
  437. to display the map anyway.
  438.  
  439. All the maps are in Windows standard .DIB format but they have a
  440. VersaTrack-specific trailer. If you modify them using a painting/drawing
  441. tool, you must run mapadj.exe to add the trailer. You can also add your own
  442. maps if they are written in the standard .DIB format and you append the
  443. VersaTrack trailer. The trailer specifies the min. and max. latitude and
  444. longitude information for a given map file.
  445.  
  446. 8.1  World Map
  447.  
  448. Clicking on this button will cause VersaTrack to draw the world map.
  449. If Real-time Display (RTD) is active, the operation of the real-time
  450. display will be frozen for the duration of the drawing operation.
  451. Any previous ground track image will be erased.
  452.  
  453.  
  454. 8.2  U.S.A. Map
  455.  
  456. Clicking on this button will cause VersaTrack to draw the map of
  457. the United States. If Real-time Display (RTD) is active, the operation
  458. of the real-time display will be frozen for the duration of the drawing
  459. operation. Any ground track image that may have been drawn prior to
  460. this command will be erased.
  461.  
  462.  
  463. 8.3  Redraw Map
  464.  
  465. Clicking on this button will redraw the current map. Any previous
  466. ground track image will be erased. If the Real-time Display is active,
  467. its operation will be frozen for the duration of the re-drawing
  468. operation.
  469.  
  470.  
  471. 8.4  GTR (Ground Track Report)
  472.  
  473. When this button is clicked, VersaTrack draws the ground track
  474. for the satellite for the primary selection using the "Start Time",
  475. "Duration", "Ground Trk Step Time", and "Min. Elevation". At the same
  476. time, a tabular human readable report is also generated and written
  477. to a disk file. The default name of the file is "GTR.OUT", but you can
  478. change it via the "GTR Filename" button. For the tabular report, the
  479. "Minimun Elevation" parameter associated with the primary selection
  480. is used to limit the lenght of the report. Only portions of the ground track
  481. that are visible from the associated site will be written out to the file.
  482. The time in the tabular report is converted to reflect the format selected
  483. for the entry (via "Report Ground Track Time in:" in the "Selections"
  484. dialog box.) The resolution of the graphical, as well as the
  485. tabular format is determined by the "Step Time" attribute of
  486. the entry. If a map of a "small" area is being displayed, the
  487. computation step time should be chosen small enough to produce
  488. a continous and smooth graph. The Color of the graph can be changed by
  489. going through the "Colors" dialog box.
  490.  
  491. Activating "GTR" while the real-time display is running, will cancel
  492. (and terminate) the real-time display.
  493.  
  494. Clicking on "STOP" button, in the menu on VersaTrack's main window
  495. will cancel an on-going Ground Track Report. A warning note will
  496. be written to the tabular report to indicate early termination of the report.
  497.  
  498.  
  499. 8.5  RTD (Real-time Display)
  500.  
  501. When this button is clicked, VersaTrack will start displaying
  502. annotated sub-satellite points for all the entries of the active list.
  503. Also, for each entry, a dialog box will be created and displayed. RTD is
  504. a resource intensive operation. For each entry of the active list,
  505. VersaTrack creates a separate execution thread, allocates several Kbytes
  506. of memory, and creates a separate window. At intervals approximately equal
  507. to the "Pos. Update" attribute of each entry, the corresponding thread will
  508. run set of CPU and FPP intensive operations.
  509.  
  510. You can have VersaTrack open up the icon for a given satellite-site pair when
  511. the satellite becomes visible from the site, by choosing from the
  512. "On Approach:" box, the "Pop up Icon" attribute for the entry. Similarly,
  513. you can have VersaTrack generate an audiable chirp (an octave's worth) when
  514. the satellite becomes visible. The default dispositions of each of the created
  515. dialog boxes (that is to say, whether you want them to be normally iconic, or
  516. opened up) can be chosen by toggling the "Keep Iconic" attribute. If the
  517. dialog box is to be displayed iconically, you can have VersaTrack blink its
  518. title bar upon visibility, by toggling the "Blick Icon" attribute.
  519. Toggling the "Blink on Map" attribute will enable or disable the continuous
  520. blinking of the sub satellite point on the map during the real-time display.
  521. The reported time is adjusted according the the format selected for the
  522. item in the "Real-time Display Time in:" attribute.
  523. The "Hide Icon" attribute when selected will inhibit the display of the
  524. icon for a given entry. There is a bug in the current version that causes
  525. some anomalous display of the icon's title bar (!!) when this attribute is
  526. turned on, but nonetheless, it can avoid some of the clutter if you have
  527. a large number of entries in the active list.
  528.  
  529. When a satellite is not visible, VersaTrack still displays the values
  530. for Azimuth, Elevation, Doppler, etc. in the Real-time Display dialog box for
  531. that satellite. These values, although mathematically correct, have
  532. virtually no practical use.
  533.  
  534. You can stop the real-time display of one or more entries by opening
  535. the icon (i.e., double clicking on the icon), and then clicking on the
  536. button labeled "Stop". To restart the real-time display for all the "stopped"
  537. entries, simply click on "RTD" again. Currently there's no provision for
  538. *selectively starting* the real-time display for individual entries of
  539. the active list.
  540.  
  541. Whenever the real-time display is running, you can change your primary
  542. selection by moving the cursor over the sub-satellite point and clicking.
  543. This will not only toggle the state of the real-time display dialog box
  544. for that entry (iconic or opened up), but it also will make that entry the
  545. "primary entry". This is the second method of changing the primary selection
  546. (as opposed to going through the "Settings" dialog box.) Note, however,
  547. that double-clicking on the an icon (to open it up) does not change
  548. the primary selection.
  549.  
  550. To stop the real-time display for all entries, click on "STOP" in
  551. VersaTrack's main window menu. "Please Wait..." will appear in the window
  552. title and RTD will be terminated for all entries of the active list.
  553. If you to stop the real-time display for individual entries, you should
  554. first open the the desired icons and click on the "STOP" button in each
  555. of the "opened-up" dialog boxes.
  556.  
  557. If you click on "GTR" while the real-time display is active,
  558. the real-time display will be canceled (i.e., stopped), and
  559. the Ground Track Report will subsequently commence. In such
  560. cases, if you need the real-time display, you must re-start
  561. it manually.
  562.  
  563.  
  564. 8.6  Rise/Set Times
  565.  
  566. Clicking on this button will display a dialog box that will show
  567. the next AOS/LOS times for the primary entry. As you click on
  568. the "Next" button in that dialog box, the next AOS/LOS times,
  569. the pass duration and the predicted maximum elevation and approximate
  570. direction of travel (relative to the site) will be displayed.
  571.  
  572. This operation is independent of GTR or RTD and can be done
  573. while either one of them is in progress.
  574.  
  575. The "Next" operation is limited by the "Duration" attribute of
  576. the primary selection. The computation of the Rise/Set times
  577. starts at the time specified for the "Start Time" attribute
  578. of the primary entry. The displayed time is adjusted to
  579. reflect the time format chosen for "Ground Track Report Time".
  580. The duration is displayed in days:hours:minutes:seconds.
  581.  
  582. If you activate this option while the satellite is in view,
  583. and the selected "Start Time" for the entry is "*" (i.e, "now"),
  584. then the rise or (AOS) time will not be the time that the
  585. bird's elevation went above the entry's threshold ("Min Elevation").
  586. It will be the time when you clicked the "Rise/Set Times" button.
  587.  
  588. 8.7  STOP
  589.  
  590. Clicking this button will terminate any on-going real-time display
  591. or ground track report operation. Otherwise it has no effect. It
  592. will not affect the service thread that may have been previously
  593. started for connection to an external module (rotator / radio server, etc).
  594.  
  595.  
  596. 8.8  GTR File Name
  597.  
  598. Clicking this button will display a dialog box that lets you
  599. change the name of the disk file into which VersaTrack writes
  600. the tabular Ground Track Report.
  601.  
  602.  
  603. 8.8 Colors
  604.  
  605. You can change the colors of the sub-satellite points and the
  606. satellite annotations during RTD, or the color of the ground
  607. track trace on the map, by clicking on this button. You can
  608. only do this if the Real-time Display or the Ground Track Report
  609. operations are not in progress. During the Real-time Display,
  610. the chosen color for "satellite" and "satellite annoations" will be
  611. XOR'ed with the displayed map colors and what you see will be the
  612. resulting colors.
  613.  
  614.  
  615. 8.9 Uninstall
  616.  
  617. Clicking this button will remove the entries that VersaTrack
  618. has previously entered into Windows-NT system Registry, effectively
  619. uninstalling VersaTrack for the current user. The program will then
  620. terminate.
  621.  
  622. 8.10 Starting External Modules
  623.  
  624. Two of the buttons on VersaTrack's main menu are used for invoking
  625. external "servers" to which VersaTrack can send data for the primary
  626. selection during the Real-time Display. The lables that will appear
  627. on these buttons are specified via the tokens given in the default
  628. files "radio.dat" and "rotator.dat". Refer to Section 10 for more
  629. details about the operation of the external modules.
  630.  
  631.  
  632. 8.11  Copyrights
  633.  
  634. Clicking on this button will display the copyright information, distribution
  635. and usage rights and restrictions, etc.
  636.  
  637.  
  638. 8.12  Help
  639.  
  640. Clicking on this button will launch help32.exe passing to it
  641. "versatrack.hlp". Unfortunately, version 1.2 does not have a help file!
  642.  
  643. 9.0  UNITS OF MEASURE
  644.      ----------------
  645.  
  646. Unless otherwise noted, VersaTrack uses the following units in its displays:
  647.  
  648.     INTERVAL TIME:  Seconds. The "Next Rise/Set Time" command
  649.                     uses  days:hours:minutes:seconds for its display.
  650.  
  651.     ELEVATION:      Degrees [ -90..90 ]   Local Horizon = 0.0
  652.     AZIMUTH:        Degrees [ 0..360 )    North = 0.0, East = 90.0
  653.     LATTITUDE:      Degrees [ -90..90 ]   South of Equator < 0
  654.     LONGITUDE:      Degrees ( -180..180 ) West of Greenwich < 0
  655.     OTHER ANGLES:   Degrees
  656.     DISTANCE:       Kilometers
  657.     DATE:           Month/Day/Year Hours:Minutes:Seconds [TimeZoneName]
  658.                     or Month-Day-Year Hours:Minutes:Seconds [TimeZoneName]
  659.     FREQUENCY:      Hertz (except where noted.)
  660.     LIN. VELOCITY:  Km/sec.
  661.  
  662.  
  663. 10.0  EXTERNAL INTERFACE
  664.      ------------------
  665.  
  666. Versatrack has a built-in interface for communication with external programs.
  667. This interface uses independent execution threads and is based on Windows-NT's
  668. "named pipes". When VersaTrack's "Real-time Display" is active, two external
  669. programs can simultaneously receive data on the primary satellite's
  670. position, and use that information, for example, to control a radio to
  671. adjust for doppler, or to steer an antenna.
  672.  
  673. Versatrack uses two regular ASCII text files to determine the titles to
  674. display on two of its menu buttons, and the corresponding names of the
  675. executables to spawn when those menu buttons are clicked. The format
  676. for the "lines" of text in the data files are:
  677.  
  678.     Model <model-name>  Drv <executable-program-name>
  679.  
  680. where <model-name> is a short name or title that Versatrack will display
  681. on a menu button reserved for this purpose, and <executable-
  682. program-name> is the name of an executable program that should exist
  683. in one of the directories listed in the PATH environment variable.
  684.  
  685. When the user clicks the button, Versatrack will first check to see if
  686. the appropriate named pipe already exists. If the pipe is there,
  687. versatrack will assume that the corresponding server is already running.
  688. It will start a service thread, and depending on whether the "real-time"
  689. mode is running or not, will either write updated data for the primary
  690. satellite, or, if the real-time mode is not running, will periodically
  691. (approx. every 30 seconds) write a special message to the pipe indicating
  692. that no data is available. This will continue until either
  693. the server terminates (and consequently the pipe is closed), in
  694. which case versatrack closes its end of the pipe and discontinues the
  695. service thread, or, versatrack terminates, in which case the server
  696. must recognize that the peer writing to the pipe has disconnected,
  697. and proceed to undertake any action that the server believes is
  698. necessary from that point on, including orderly termination of
  699. any provided service, etc.
  700.  
  701. If Versatrack cannot connect to the pipe, it will assume that
  702. the server is not already running, and will attempt to spawn
  703. the executable module via the CreateProcess() API. It will then
  704. proceed to re-connect to the pipe as outlined above.
  705.  
  706. The external module, or "server" as it will be called from here on, is
  707. responsible for creating a named pipe, listening on that pipe
  708. for an incomming connection from VersaTrack, and then reading the data from the
  709. pipe and using it for its tasks. Two such servers can run simultaneously
  710. and each uses a different named pipe. The names of the pipes are:
  711.  
  712.         \\.\PIPE\_VROTAT_   and   \\.\PIPE\_VRADIO_
  713.  
  714. As can be guessed, one is primarily intended for communication with
  715. an external program for controlling a radio, and the other for
  716. communication with an external program for controlling an antenna rotator.
  717.  
  718. No provision is currently provided to have "remote" servers, although
  719. their implementation is somewhat trivial at the API level.
  720.  
  721. Once a server starts up, it should create "its" pipe as soon as
  722. practical, and start listenning on it for a connection. If a
  723. connection is made, the server must continously read the pipe
  724. until the peer (writer) closes. A sample skeleton "radio" server is
  725. provided that shows how that can be done. The sample also has the
  726. skeleton code for reading from and writing to one of WinNt's supported
  727. COM ports (the right way). The code can be used as the starting point
  728. for writing a fancy full-fledged radio or rotator controller.
  729.  
  730. The data VersaTrack sends over the pipe(s) is in ordinary "human-readable"
  731. ASCII. All messages are written as fixed 100 byte packets and are
  732. in the form of C language strings with at least one null character at the end.
  733. A message that is exactly 100 bytes long will not have a terminating null.
  734.  
  735. The first character of a message indicates the basic type of the message.
  736. The format of the remaining characters in the message depend on the type.
  737.  
  738. There are presently 4 types of messages. They are "hello", "initialization",
  739. "data", and "interruption" messages. The following sections describe
  740. each message type in detail. Please note that wherever <space> is specified,
  741. one or more space (blank) characters may actually appear. Also, the
  742. numerical values whether decimal, hexadecimal or floating point,
  743. may have leading zeros. None of the numerical values is in octal. Strings
  744. appearing inside double quotes are literals (case sensitive).
  745.  
  746. HELLO MESSAGE:
  747.  
  748.    
  749. FORMAT:   ">"<space>"HELLO"<space>
  750.           <version><space><message protocol version><space>
  751.           "WH"<space><VersaTrack Window Handle><space>
  752.           "SEQ"<space><Starting sequence number><null>....
  753.  
  754.           <VersaTrack Window Handle> is versatrack's main window handle
  755.           as returned by WIN33 API CreateWindow(). It is formatted as a
  756.           hex value. It can be used by the server to determine the
  757.           thread-id of versatrack's main window to do periodic
  758.           PostThreadMessage()'s in order to implement a heart-beat. If the
  759.           PostThreadMessage fails, the server will know that Versatrack has
  760.           exited or terminated for some reason.
  761.           VersaTrack will receive and discard message number WM_USER+27.
  762.           So this message can be used for implemetation of a heartbeat.
  763.  
  764.           <version> is a 2 digit decimal number with the 10's digit being the
  765.           current VersaTrack major revision number and the One's digit being
  766.           the current Versatrack minor revision number.
  767.           <message protocol version> is a single digit decimal number
  768.           indicating the revision level of the messaging protocol. This
  769.           number is presently 1.
  770.           
  771.           <Starting sequence number> is a random decimal value between
  772.           0 and 15 (inclusive). Every message that follows will start off
  773.           with a sequence number with a value one higher than the one in
  774.           the previous message. This will continue until the end of the
  775.           session (i.e., another hello message).
  776.           
  777. EXAMPLE:
  778.           > HELLO 12 1 WH 04003c9f SEQ 011
  779.  
  780.           The HELLO message is sent only once at the start of the activation
  781.           of versatrack's service thread as soon as it has connected to
  782.           the server. If one instance of versatrack is terminated and
  783.           another instance is started (for whatever reason), another
  784.           HELLO message will be sent. Note, however, that meanwhile,
  785.           the pipe's client end is closed once, and a new connection
  786.           is subsequently started. In the example shown, Versatrack
  787.           version is 1.2 and it is using message format 1.
  788.  
  789. INTERRUPT MESSAGE:
  790.  
  791. FORMAT:   "!"<space><decimal sequence number><space><single-quote><text>
  792.           <single-quote><null>.....
  793.  
  794.           The decimal sequence number is the value of the previously
  795.           sent sequence number plus 1, as a signed 32 bit 2-s complement
  796.           number.
  797.  
  798.           There are currently only two interruption message strings (
  799.           for <text>):
  800.  
  801.           a) 'STOPPED'
  802.  
  803.           Is sent when Versatrack's Real-time mode has not started yet,
  804.           or is stopped after it was started. While real-time mode is
  805.           not running, this interrupt message will be continuously sent
  806.           approximately every 30 seconds. The same is also true if the
  807.           real-time display mode is stopped for the primary satellite/site
  808.           pair (e.g., by clicking the "stop" button in the dialog box
  809.           of the primary satellite/site display.) In other words, versatrack
  810.           may be running real-time displays for other satellite/site's,
  811.           but the user has stopped one or more of them, including the
  812.           the one for his "primary" selection.
  813.  
  814.           b) 'SAT CHANGED'
  815.  
  816.           Is sent whenever the user changes the 'primary' satellite/site
  817.           pair in Versatrack while versatrack's real-time mode is running.
  818.           It can be used by the server to take any appropriate action
  819.           needed for proper operation of the server and the device it
  820.           controls (if any.) The single quotes are parts of the message.
  821.  
  822.           In a) and b) above, single quotes are for readability only.
  823.           The actual message will only have one single quote at the
  824.           beginning and one at the end of the text string.
  825.           
  826.  
  827. EXAMPLE:    ! 2091 'SAT CHANGED'
  828.                - or -
  829.             ! 776 'STOPPED'
  830.  
  831.  
  832. INITIALIZATION MESSAGE
  833.           
  834. FORMAT:   "*"<space><decimal sequence number><space>"INIT UPD"<space>
  835.           <data update interval in seconds><space>"MD"<space>
  836.           <satellite's op mode><space>"MIE"<space><minimum elevation><space>
  837.           "SITE"<space><single quote><site name><single quote><space>"SAT"
  838.           <space><single quote><satellite name><single quote><null>.....
  839.  
  840.           decimal sequence number is as described before. The Data
  841.           update interval is the approximate number of seconds (in decimal)
  842.           between data messages sent by VersaTrack. This number can be used,
  843.           for example, by the control server for interpolation of the
  844.           parameters based on prior messages, etc.
  845.           The satellite's operation mode is a 3 character string
  846.           that indicates which satellite's transponder is active.
  847.           Versatrack uses the data supplied in its "modes" data file
  848.           along with the position of the satellite in its orbit
  849.           to come up with this string. If no mode is given for
  850.           the satellite in VersaTrack's modes file, then the
  851.           data will be either null (i.e., two consecutive single quotes ''),
  852.           or 'N/A'.
  853.  
  854.           Minimum elevation is a decimal floating point value (in units
  855.           of degrees above site's local horizon). It is one of the
  856.           attributes specified by the user via the "Settings" dialog box.
  857.           It can be used by the control server to warn the user and
  858.           gracefully start or stop the device it controls (such as a radio
  859.           or antenna otator).
  860.           
  861.           Site and Sat names are the corresponding satellite and
  862.           site names for the currently selected "primary" satellite/site
  863.           pair in VersaTrack.
  864.  
  865.           Every time the user changes the primary satellite/site
  866.           pair while Versatrack's real-time mode is on, An interrupt
  867.           message, followed by an initialization message is sent to
  868.           the control server.
  869.  
  870. EXAMPLE:
  871.           * INIT 356 UPD 5 MD '  S' MIE 10.0 SITE 'Austin, Texas' SAT 'AO-13'
  872.  
  873.  
  874. DATA MESSAGE:
  875.  
  876. FORMAT:   "+"<space><decimal sequence number><space>
  877.           "AZ"<space><degrees Azimuth><space>
  878.           "EL"<space><degrees Elevation><space>
  879.           "RNG"<space><killometer's range from observer's site><space>
  880.           "DV"<space><satellite speed in killometers per second><space>
  881.           "PL"<space><path loss in DB><space>
  882.           <satellite name><null>....
  883.  
  884.           (note that satellite name is not in single or double quotes).
  885.  
  886.           The sequence number is as explained before.
  887.           <degrees Azimuth> and <degrees Elevation> specify the relative
  888.           position of the bird and are specified as floating point decimal
  889.           numbers. Azimuth can range from 0.0 to 360.0 (minus epsilon),
  890.           and Elevation value's range is -90.0 to +90.0.
  891.           Range is given as a floating point decimal number. It may
  892.           in some cases be given in exponential format.
  893.           Satellite's speed is given as a floating point decimal number and
  894.           can be positive (if satellite is approaching), or negative
  895.           (if satellite is receding). This value can be used to
  896.           determinte the doppler shift.
  897.           The path loss is just a theoretical value that gives a first order
  898.           indication of the the relative signal attenutation. While its use
  899.           is limited, it may be used to switch in/out pre-amplifiers, for
  900.           example. The satellite name follows all other parameters and
  901.           starts with the first non-blank character after path loss and
  902.           continues until the end of the string (either the first null
  903.           character, or end of 100 byte buffer.
  904.  
  905. EXAMPLE:  + 077 AZ 261.5 EL 22.7 RNG 789.02331 DV -4.27283121 PL 164.1 DO-17
  906.  
  907. NOTES:
  908.           Any of the INTERRUPT messages can occur at any time after the
  909.           HELLO message. This means they can appear right after hello,
  910.           before or after INIT, and in the middle of data messages.
  911.           One type of INTERRUPT message may be followed by another with or
  912.           without any other intervening message(s).
  913.  
  914.           Also, An INIT message is not garanteed to be followed by a
  915.           data message, but a DATA message will always be sent sometime
  916.           after an INIT message. Normally a data message will immediately
  917.           follow an INIT, but sometimes one or more INTERRUPT messages
  918.           may appear between them.
  919.  
  920.           The only type of message that can appear right after
  921.           an INTERRUPT message with a 'SAT CHANGED' text, is either
  922.           an INTERRUPT message with a 'STOPPED' text, or an INIT message.
  923.           
  924.  
  925. TYPICAL SESSION:
  926.  
  927.           (The numerical data for the satellites are all made up and may
  928.            or may not make any sense)
  929.  
  930.           > HELLO 12 1 WH 00005e00 SEQ 011
  931.           ! 012 'STOPPED'
  932.           ! 013 'STOPPED'
  933.           ...
  934.           ...
  935.           ! 040 'STOPPED'
  936.                      <- user clicks on RTD in VersaTrack
  937.  
  938.           * INIT 041 UPD 5 MD ' FM' MIE 10.0 SITE 'Austin, Texas' SAT 'DO-17'
  939.           + 042 AZ 220.9 EL -37.2 RNG 5467.92821 DV -2.0187783 PL 240.6 DO-17
  940.           + 043 AZ 221.1 EL -37.1 RNG 5453.18010 DV -2.0093974 PL 240.6 DO-17
  941.           + 044 AZ 221.1 EL -37.4 RNG 5447.73274 DV -1.9741230 PL 240.6 DO-17
  942.           + 045 AZ 221.2 EL -37.6 RNG 5441.86544 DV -1.9690811 PL 240.5 DO-17
  943.           + 046 AZ 221.2 EL -37.9 RNG 5436.65155 DV -2.8019801 PL 240.5 DO-17
  944.           ...
  945.           ...         <- user selects another sat
  946.           ...
  947.           ! 173 'SAT CHANGED'
  948.           * INIT 174 UPD 120 MD ' S' MIE 15.0 SITE 'Austin, Texas' SAT 'AO-13'
  949.           + 175 AZ 66.0 EL 28.9 RNG 13389.1 DV 6.2972171 PL 181.9 AO-13
  950.           ...
  951.           ...         <- user stops the real-time display for AO-13.
  952.           ! 176 'STOPPED'
  953.           ! 177 'STOPPED'
  954.           ...
  955.  
  956. 11.0   MISC
  957.        ----
  958. 11.1   Data Files
  959.  
  960. Lines starting with '#' and those containing only spaces or tabs
  961. are treated in most data files, as comments.
  962.  
  963. The Two-line Element set file can have duplicate entries for a
  964. satellite. VersaTrack will pick up the element set with the highest
  965. sequence number. Duplicate satellite names whose catalog number
  966. don't agree, or duplicate catalog numbers whose names don't agree
  967. will be flagged to the user. Commnet lines are recognized and skipped.
  968. The order of the entries are not important as they will be sorted after
  969. the entire file is read.
  970.  
  971. The rotator and radio data files can have serveral records. However,
  972. only the first record (line of text) will be used. In all cases
  973. records must be syntactically correct or the results will be upredictable.
  974.  
  975. Although the entries in the Sites file will sorted by VersaTrack, it
  976. is a good idea to keep the alphabetical order intact for easeier
  977. modification and management.
  978.  
  979. 11.2  Ground Track Report Start Time
  980.       ------------------------------
  981.  
  982. You can append "UTC", "LOC", or your local time zone name to the date and
  983. time that you enter for the "Start Time" in the "Settings" dialog box.
  984. Versatrack will convert this date/time to UTC and store it in that format.
  985.  
  986.  
  987. --END OF DOCUMENT--
  988.